---
type: integration
title: '@astrojs/tailwind'
description: 了解如何在你的 Astro 项目中使用 @astrojs/tailwind 集成。
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/tailwind/'
category: other
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';

**[Astro 集成][astro-integration]** 为你项目中的每一个 `.astro` 文件和 [框架组件](/zh-cn/guides/framework-components/) 带来 [Tailwind](https://tailwindcss.com/) 的实用 CSS 类，同时支持 Tailwind 配置文件。

## 为什么是 Tailwind？

Tailwind 让你直接使用实用类而不是编写 CSS。这些实用类大多与某个 CSS 属性设置一一对应：例如，在一个元素上添加`text-lg`，相当于在 CSS 中设置`font-size: 1.125rem`。你也许会发现使用这些预定义的实用类更容易编写和维护你的样式！

如果你不喜欢这些预定义的设置，你可以根据你项目的设计要求[定制 Tailwind 配置文件](https://tailwindcss.com/docs/configuration)。例如，如果你设计中的“大文本”实际上是`2rem`，你可以将[`lg`字体大小设置](https://tailwindcss.com/docs/font-size#customizing-your-theme)改为`2rem`。

Tailwind 也是为 React、Preact 或 Solid 组件添加样式的不错选择，这些组件不支持组件文件中的 `<style>` 标签。

注意：一般来说，我们不鼓励在同一个文件中同时使用 Tailwind 和另一种样式方法（例如，样式组件）。

## 安装

Astro 包含了一个 `astro add` 命令，用于自动设置官方集成。如果你愿意，可以改为[手动安装集成](#手动安装)。

在新的终端窗口中运行以下其中一个命令。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add tailwind
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add tailwind
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add tailwind
  ```
  </Fragment>
</PackageManagerTabs>

如果你遇到任何问题，[请随时在 GitHub 上向我们报告](https://github.com/withastro/astro/issues)并尝试下面的手动安装步骤。

### 手动安装

首先，使用你的包管理器安装 `@astrojs/tailwind` 和 `tailwindcss`。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/tailwind tailwindcss
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/tailwind tailwindcss
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/tailwind tailwindcss
  ```
  </Fragment>
</PackageManagerTabs>

然后，使用 `integrations` 属性将集成应用到你的 Astro 配置文件中：

```js ins={2} ins="tailwind()" title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
export default defineConfig({
  // ...
  integrations: [tailwind()],
});
```

然后，在你的项目根目录下创建一个 `tailwind.config.mjs` 文件。你可以使用以下命令来生成一个基本的配置文件：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx tailwindcss init
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm dlx tailwindcss init
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn dlx tailwindcss init
  ```
  </Fragment>
</PackageManagerTabs>

最后，可将如下基本配置添加到你的 `tailwind.config.mjs` 文件中：

```js ins={3} title="tailwind.config.mjs" "content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}']"
/** @type {import('tailwindcss').Config} */
export default {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

## 使用

当你安装集成后，Tailwind 的实用类应该马上就可以使用了。前往 [Tailwind 文档](https://tailwindcss.com/docs/utility-first)学习如何使用 Tailwind，如果你看到一个你想尝试的实用类，就把它添加到你项目的任何 HTML 元素中去吧！

[Autoprefixer](https://github.com/postcss/autoprefixer) 也是在开发模式和生产模式下工作时自动设置的，所以 Tailwind 类将在旧的浏览器中工作。

## 配置

### 配置 Tailwind

如果你使用了快速安装，并且每个选项都选是，你会在你项目的根目录下看到一个 `tailwind.config.mjs` 文件。使用这个文件来修改你的 Tailwind 配置。你可以[在 Tailwind 文档中](https://tailwindcss.com/docs/configuration)学习如何使用这个文件来定制 Tailwind。

如果没有该文件，你可以在根目录下添加你自己的 `tailwind.config.(js|cjs|mjs|ts|mts|cts)` 文件，集成将使用其配置。如果你已经在另一个项目中配置了 Tailwind，并想把这些设置带到这个项目中来，这也不错。

### 配置集成

Astro Tailwind 集成处理 Astro 和 Tailwind 之间的通信，它有自己的设置。在 `astro.config.mjs` 文件（*不是* Tailwind 配置文件）中改变这些，这里是你项目的集成设置所在。

#### configFile

以前在 `@astrojs/tailwind` v3 中被称为 `config.path`。请参阅 [v4 更改日志](https://github.com/withastro/astro/blob/main/packages/integrations/tailwind/CHANGELOG.md#400) 以更新你的配置。

如果你想使用不同的 Tailwind 配置文件，而不是默认的 `tailwind.config.(js|cjs|mjs|ts|mts|cts)`，请使用本集成的 `configFile` 选项指定该文件的位置。如果 `configFile` 是相对路径，则会相对于当前工作目录解析。

:::caution
不建议改变这一点，因为它可能导致与 Tailwind 整合的其他工具出现问题，比如官方的 Tailwind VSCode 扩展。
:::

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // 示例：为 Tailwind 配置文件提供一个自定义路径
      configFile: './custom-config.mjs',
    }),
  ],
});
```

#### applyBaseStyles

以前在 `@astrojs/tailwind` v3 中被称为 `config.applyBaseStyles`。请参阅 v4 更改日志以更新你的配置。

默认情况下，该集成在你项目的每个页面上都导入一个基本的 `base.css` 文件。这个基本的 CSS 文件包括三个主要的 `@tailwind` 指令：

```css title="base.css"
/* 集成的默认注入的 base.css 文件 */
@tailwind base;
@tailwind components;
@tailwind utilities;
```

要禁用这个默认行为，请将 `applyBaseStyles` 设置为 `false`。如果你需要定义你自己的 `base.css` 文件（例如包括一个[`@layer` 指令](https://tailwindcss.com/docs/functions-and-directives#layer)），这可能很有用。如果你不希望 `base.css` 被导入你的项目的每一个页面，这也很有用。

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // 示例：在每个页面上禁用注入基本的`base.css`导入。
      // 如果你需要定义或导入你自己的 "base.css"，这很有用。
      applyBaseStyles: false,
    }),
  ],
});
```

你现在可以[导入你自己的 `base.css` 作为本地样式表](/zh-cn/guides/styling/#导入本地样式表) 。

#### nesting

设置为 `true` 以应用 [`tailwindcss/nesting` PostCSS 插件](https://tailwindcss.com/docs/using-with-preprocessors#nesting)，这样你就可以在兼容 Tailwind 语法的基础上编写嵌套的 CSS 声明。此选项默认为 `false`。

```js ins="nesting: true"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  integrations: [
    tailwind({
      // 示例：允许在 Tailwind 的语法基础上编写嵌套的 CSS 声明
      nesting: true,
    }),
  ],
});
```

## 例子

* [Astro Tailwind Starter](https://github.com/withastro/astro/tree/latest/examples/with-tailwindcss?on=github) 为你提供一个基础的、使用 Tailwind 进行样式设计的可运行项目
* Astro 的主页使用 Tailwind。查看其 [Tailwind 配置文件](https://github.com/withastro/astro.build/blob/main/tailwind.config.ts)或[示例组件](https://github.com/withastro/astro.build/blob/main/src/components/Checkbox.astro)
* [Astro Ink](https://github.com/one-aalam/astro-ink)、[Sarissa Blog](https://github.com/iozcelik/SarissaBlogAstroStarter)、[Astro Tech Blog](https://github.com/nicdun/astro-tech-blog)和 [Creek](https://github.com/robertguss/Astro-Theme-Creek) 主题使用 Tailwind 进行样式设计
* [浏览 GitHub 上的 Astro Tailwind 项目](https://github.com/search?q=%22%40astrojs%2Ftailwind%22%3A+path%3A%2Fpackage.json\type=code)以获得更多的例子！

## 故障排除

### 使用 `@apply` 指令时提示类不存在

当在 Astro、Vue、Svelte 或其他组件集成的 `<style>` 标签中使用 `@apply` 指令时，它可能会产生关于你的自定义 Tailwind 类不存在的错误，并导致你的构建失败。

```sh
error   The `text-special` class does not exist. If `text-special` is a custom class, make sure it is defined within a `@layer` directive.
```

通过在你的 Tailwind 配置中添加一个插件来定义你的自定义样式来修复它，[而不是在全局样式表中使用`@layer`指令](https://tailwindcss.com/docs/functions-and-directives#using-apply-with-per-component-css)，添加如下内容：

```js title="tailwind.config.mjs"
export default {
  // ...
  plugins: [
    function ({ addComponents, theme }) {
      addComponents({
        '.btn': {
          padding: theme('spacing.4'),
          margin: 'auto',
        },
      });
    },
  ],
};
```

### 基于类的修改器不能与 `@apply` 指令一起工作

某些带有修饰符的 Tailwind 类依赖于跨多个元素的组合类。例如，`group-hover:text-gray` 编译为 `.group:hover .text-gray`。当这与 Astro `<style>` 标签中的 `@apply` 指令一起使用时，编译后的样式会从构建输出中删除，因为它们与 `.astro` 文件中的任何标记不匹配。同样的问题也可能发生在支持范围样式的框架组件中，如 Vue 和 Svelte。

为了解决这个问题，你可以使用内联类来代替：

```html "text-black group-hover:text-gray"
<p class="text-black group-hover:text-gray">Astro</p>
```

### 其他

* 如果你的安装似乎不成功，尝试重新启动开发服务器。
* 如果你编辑并保存了一个文件，但没有看到你的网站有相应的更新，试着刷新页面。
* 如果刷新页面并没有更新你的预览，或者新的安装似乎没有效果，那么就重新启动开发服务器。

如需帮助，请查看 [Discord](https://astro.build/chat) 上的 `#support` 频道。我们友好的支持小组成员将在这里提供帮助！

你也可以查看我们的 [Astro 集成文档][astro-integration]，了解更多关于集成的信息。

[astro-integration]: /zh-cn/guides/integrations-guide/

[astro-ui-frameworks]: /zh-cn/guides/framework-components/#使用框架组件
